package co.yixiang.yshop.module.infra.api.file;

/**
 * 文件 API 接口
 *
 * @author yshop
 */
public interface FileApi {

    /**
     * 保存文件，并返回文件的访问路径
     *
     * @param content 文件内容
     * @return 文件路径
     */
    default String createFile(byte[] content) {
        return createFile(null, null, content);
    }

    /**
     * 保存文件，并返回文件的访问路径
     *
     * @param path 文件路径
     * @param content 文件内容
     * @return 文件路径
     */
    default String createFile(String path, byte[] content) {
        return createFile(null, path, content);
    }

    /**
     * 保存文件，并返回文件的访问路径
     *
     * @param name 文件名称
     * @param path 文件路径
     * @param content 文件内容
     * @return 文件路径
     */
    String createFile(String name, String path, byte[] content);

    /**
     * 根据路径前缀查询文件，按 id 倒序，支持限制条数
     *
     * @param pathPrefix 路径前缀，例如 "captcha/images/car/"
     * @param limit 限制数量，空为不限制
     * @return 文件简要信息列表
     */
    java.util.List<FileSimpleRespDTO> getFilesByPathPrefix(String pathPrefix, Integer limit);

    /**
     * 删除文件
     *
     * @param id 文件编号
     */
    void deleteFile(Long id);

}
